home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / edithook.doc < prev    next >
Text File  |  1996-09-05  |  5KB  |  136 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/Edit_Hook
  4. dopus5.library/FreeEditHook
  5. dopus5.library/GetEditHook
  6. dopus5.library/GetSecureString
  7. dopus5.library/Edit_Hook                             dopus5.library/Edit_Hook
  8.  
  9.     PURPOSE
  10.  
  11.     The dopus5.library provides an edit hook which you can attach to string
  12.     gadgets, to take advantage of some additional features. The features
  13.     provided by the edit hook include :
  14.  
  15.         - Enhanced cursor movement using alt and shift
  16.         - History using up/down cursor
  17.         - Clipboard support (copy, cut and paste)
  18.         - Optional filtering of path characters
  19.         - Secure option where string is not displayed
  20.         - Return automatically activates the next string gadget
  21.         - Key press notification
  22.  
  23.     To use the edit hook in your gadgets, you must obtain a Hook structure
  24.     with the GetEditHook() function. Once you have finished with it, you
  25.     must free this with FreeEditHook().
  26.  
  27. dopus5.library/FreeEditHook                       dopus5.library/FreeEditHook
  28.  
  29.     NAME
  30.         FreeEditHook - free a Hook created with GetEditHook()
  31.  
  32.     SYNOPSIS
  33.         FreeEditHook(hook)
  34.                       A0
  35.  
  36.         void FreeEditHook(struct Hook *);
  37.  
  38.     FUNCTION
  39.         This routine frees a Hook that you obtained via a call to
  40.         GetEditHook().
  41.  
  42.     INPUTS
  43.         hook - hook to free
  44.  
  45.     SEE ALSO
  46.         GetEditHook()
  47.  
  48. dopus5.library/GetEditHook                         dopus5.library/GetEditHook
  49.  
  50.     NAME
  51.         GetEditHook - get a Hook pointer to access the edit hook
  52.  
  53.     SYNOPSIS
  54.         GetEditHook(type, flags, tags)
  55.                      D0     D1    A0
  56.  
  57.         struct Hook *GetEditHook(ULONG, ULONG, struct TagItem *);
  58.  
  59.         struct Hook *GetEditHookTags(ULONG, ULONG, Tag, ...);
  60.  
  61.     FUNCTION
  62.         This routine returns a Hook structure that you can use to give
  63.         the additional capabilities to your string gadgets.
  64.  
  65.     INPUTS
  66.         type - type of Hook (only HOOKTYPE_STANDARD is valid so far)
  67.         flags - a combination of the following flags :
  68.  
  69.                 EDITF_NO_SELECT_NEXT - stops the return key from
  70.                 automatically activating the next (or previous, with shift)
  71.                 string gadget.
  72.  
  73.                 EDITF_PATH_FILTER - filters path characters out of the
  74.                 string (/ and :)
  75.  
  76.                 EDITF_SECURE - secure password field, doesn't display the
  77.                 characters that are typed. If this flag is specified, the
  78.                 gadget's StringInfo->MaxChars value must be twice what
  79.                 it would ordinarily be. The gadget's StringInfo->Buffer
  80.                 must be this size plus an additional two bytes, eg
  81.                 (max_len*2)+2.
  82.  
  83.         tags - the following tags are supported by the edit hook :
  84.  
  85.                EH_History - supplies a pointer to an Att_List structure
  86.                which contains the history list for this gadget. Each entry
  87.                in the list is the name of a node, with the most recent node
  88.                at the end of the list. The Att_List should be created using
  89.                Semaphore locking.
  90.  
  91.                EH_ChangeSigTask - allows you to specify a task that is to be
  92.                signalled whenever the contents of the string gadget are
  93.                changed by the user. This allows you to have a display
  94.                dynamically updated as the user types.
  95.  
  96.                EH_ChangeSigBit - the signal bit used to signal your task.
  97.                This is the bit number, not a mask.
  98.  
  99.     RESULT
  100.         Returns a pointer to a Hook structure which you can use for your
  101.         gadget. It is not a good idea to share hooks between gadgets
  102.         (although unless you are using the EH_History facility it should
  103.         not really be a problem).
  104.  
  105.     SEE ALSO
  106.         FreeEditHook(), GetSecureString(), Att_NewList()
  107.  
  108. dopus5.library/GetSecureString                 dopus5.library/GetSecureString
  109.  
  110.     NAME
  111.         GetSecureString - retrieve the real string from a secure field
  112.  
  113.     SYNOPSIS
  114.         GetSecureString(gadget)
  115.                           A0
  116.  
  117.         char *GetSecureString(struct Gadget *);
  118.  
  119.     FUNCTION
  120.         The secure feature of the edit hook is implemented using a buffer for
  121.         the gadget that is twice as large plus 2 bytes as it would
  122.         ordinarily be. This is because the first half of the buffer is filled
  123.         with * characters as the user types. The real text is stored in the
  124.         second half of the buffer.
  125.  
  126.     INPUTS
  127.         gadget - secure string gadget
  128.  
  129.     RESULT
  130.         Returns a pointer to the real text for the gadget. The text is
  131.         properly null-terminated.
  132.  
  133.     SEE ALSO
  134.         GetEditHook()
  135.  
  136.